NewtNews.txt
10/15/94
S. Weyer

Read Newt.1st first. 

Contents
- About Newt
- Revision History
- Introduction
  Learners or Programmers?
  Newt and Turtle and Logo
  Newt (and RUNewt) and Newton ToolKit (NTK) and NewtonScript
  Newt in the News
  For Further Info
  Registration/Shareware and Freeware
  Current List of Examples
  Programming WARNING -- Newt and You
- Getting Started
  Where to Find Newt and RUNewt
  Exploring Newt's Turtle Personality
  Exploring Newt's Application Personality
- Interface Guide
  Main (Edit Methods/Objects)
  Eval Controls
  Newt Drawing
  Newt Controls
  Eval Log
  About
  RUNewt, Slurpee,...
  Edit Methods/Objects (continued)
  Preferences
- NewtonScript
  Syntax
  Errors
- Possible Future Steps
- Personal History

=====
About Newt 2.4:
a native development environment for simple applications using NewtonScript,
and creating turtle-like graphics using gestures, buttons, and NS.

Keywords: object-oriented programming, application development environment,
NewtonScript, NTK, learning, graphics, mathematics, Logo.

Copyright S. Weyer 1993, 1994, All Rights Reserved Worldwide.

Newt is shareware. It may be freely distributed via online services and
bulletin boards if it is unmodified and includes the file NewtNews.txt. It may
not be commercially bundled or redistributed on CD-ROM, floppy disk, PCMCIA,
networks or other media without my permission. Please continue reading for
help, examples, warnings and other information.

After several days of trial use, please register your copy by sending a check
for $35 (see Shareware and Freeware) to the author. Tap overview, select About
Newt, tap Save to save a Registration Form in Notepad. In return, I will
provide you with a printed manual that introduces NewtonScript and describes
Newt features, a floppy containing current releases and source code for a
variety of examples, and priority in responding to requests.

Stephen Weyer
17 Timber Knoll Drive
Washington Crossing, PA 18977-1052
Internet: weyer@guest.apple.com
America Online/eWorld/NewtonMail: SteveWeyer
Compuserve: 74603,2051
AppleLink: WEYER.S

=====
Revision History

2.4 (10/15/94)
-- see Newt.1st (and change24.txt for registered users)

2.3 (9/3/94)
- adds new syntax/mechanism for defining objects and building apps
- supports embedded help books and standalone Newton books
- provides scroll options for long lists of methods, objects
- adds other apps/books to Newt's overview list, e.g., Slurpee
- uses a "library" folder for shared, customizable method/object templates
- supports Duplicate, Delete of source code via action button
- removes built-in demo code; see sample sources applic0.nwt, graphic0.nwt;
  see also NewtATut and/or NewtTurT interactive tutorials
- lite-version (w/o turtle graphics and some features) available separately
- both Mac and PC versions of text files
- misc. changes to methods, user interface


2.2 (6/6/94):
- support and examples for additional system prototypes and viewclasses
  (it now supports all prototypes and viewclasses described in NTK 1.0.1):
  protoRCheckbox, protoFilingButton, protoDrawer, protoDateExpando,
  protoPhoneExpando, protoActionButton, protoPrintFormat, protoKeyboard,
  protoKeypad, protoLabeledBatteryGauge, protoPicker, protoEndPoint,
  clView, clEditView, clGaugeView, clKeyboardView, clMonthView, clOutline,
  clParagraphView, clPictureView, clPolygonView, clRemoteView
- a few other fixes/features

2.1 (4/20/94):
- reorganizes interface: Edit Methods moves to "main" view, turtle to Drawing
  Area; other cosmetic improvements
- supports and documents additional system prototypes: protoBorder,
  protoCloseBox, protoDivider, protoFloater, protoFolderTab, protoGauge,
  protoGlance, protoLabelInputLine, protoLargeCloseBox, protoPictIndexer,
  protoPictRadioButton, protoPictureButton, protoRoll, protoRollBrowser,
  protoRollItem, protoSetClock, protoShowBar, protoStatus, protoStatusBar,
  protoTable, protoTableDef, protoTableEntry, protoTitle
- supports user prototypes and subviews ("linked layouts")
- handles low frame heap situations better
- adds Color (penPattern) option for Newt drawing

2.0 (2/16/94):
- adds initial support for creating interface objects and saving applications
- new icon; "auto close"; separate RUNewt application for running, exchanging
  applications
- rearranges/resizes interface for Newt Controls, Eval Controls, Code
  Templates, Edit Methods (continued)
- moves samples to Expr button, overview accesses list of views
- sets keyboard input to a default edit location (Eval field or method source)
- saves folder for "newts" to/from Preferences; does not remove Preferences as in 1.1
- improves access for large and larger numbers of method entries
- adds visual feedback for Pen setting -- Newt grows/shrinks
- adds support for Logo word and sentence operations

1.2 (12/93-2/94)
- limited distribution beta releases; Happy Newt Year

1.1 (11/24/93):
- saves Newt methods, screen snapshots and evaluation results as "newts"
  (notes) in Notepad, organized via the built-in folders
- sends messages to single newt or to many newts
- adds a Print?option, with results and errors printed to a popup scrolling Eval Log
- eliminates the "do you want to add..." prompts during keyboard entry
- streamlines NewtonScript editing via inserting code templates in Edit
  Methods (continued) and via selecting entire sample expressions for Eval field
- recognizes line gesture to set Newt heading and to draw lines; drag to move Newt
- draws more cleanly (clipping, refresh); adds "poof" animation for erase
- simplifies interface for editing methods; scrolls methods
- traps and reports errors
- removes Preferences entry when Newt application is removed

1.0 (10/12/93)
- initial release

=====
Introduction

Learners or Programmers?
You can use Newt as
- a pen-based "etch-a-sketch"
- a Logo-like turtle-graphics environment
- an introduction to NewtonScript and object-oriented programming
- a construction tool for simple views and applications
Try some of the introductory examples described under Getting Started.


Newt and Turtle and Logo
The first version of Newt was a turtle-graphics environment. "Newton Turtle"
and "NewtTurtle" seemed a bit too long, so I shortened its name to Newt, given
its amphibious similarity to its Logo cousin and also its non-turtle uses. For
exploration of Newt's "turtle personality", familiarity with Logo concepts and
turtles would be useful though not necessary. Although Newt does not
"understand" any of the Logo dialects directly, it does provide turtle
commands, and an optional module for manipulating Logo-style data structures,
i.e., words and sentences. Despite syntactic differences between NewtonScript
and Logo, you can borrow ideas and translate code from Logo materials and
books, e.g., Abelson & diSessa, books on fractals, etc.


Newt (and RUNewt) and Newton ToolKit (NTK) and NewtonScript
Newt allows you to write your own expressions and methods in NewtonScript, and
execute them directly on your Newton. NewtonScript (NS), Newton's built-in,
object-oriented (o-o) language, shares ancestry with dynamic o-o languages
like Smalltalk, Self, Common Lisp, and ObjectLogo. For more advanced users,
familiarity with o-o concepts and constructs would be useful; for others, Newt
should serve as a brief introduction to these ideas. Newt 2.0 introduced
rudimentary capabilities to create dynamic views and stand-alone applications
that can later be run or transferred using RUNewt. See RUNewt.txt for further
information. Users interested in building small applications could consider
Newt a portable prototyper, or as a learning step toward building more
complex, complete and industrial-strength applications via Apple's
desktop-based Newton ToolKit (NTK) on Macintosh (and eventually Windows). See
"Current List of Examples" for applications that can be built in Newt.


Newt in the News
"Building Native Newton Applications with Newt" appeared in PIE Developers,
Vol. 2.4, July 1994; pp.14-18.  Erica Sadun reviewed Newt's turtle personality
in the same issue. _protoReality 1.3 -- the NANUG newsletter, available as a
Newton book -- features an interview about Newt. _protoReality 1.3 & 1.4 have
articles with my daughter on using Newt to draw letters. Newt 1.0 received an
early positive review in the first issue of the (now defunct) DoubleTap
newsletter.

"Newt" is often used by the monosyllable-challenged to refer to a Newton. "Newt
is neat" could refer to the Newton itself and/or to this wonderful application
-- I will always mean the latter. Show Newt to your friends to help achieve
the worldwide goal of "Newt on every Newt"! So that Newt can appeal to many
families and orientations, it is gender "newtral" (in order to reproduce more
Newts, however, it has not been "newtered"); users should probably not call
themselves "newtists".

In other literary references, there is of course Shakespeare's famous drink
recipe: "eye of newt, ...". Tabloids will probably suggest a connection
between Newt and Elvis. This is likely, given Elvis' early career as a "lounge
lizard". However, the FBI has conspiratorially censored this from the latest
Newton ROMs [in early Newtons, you could set the Country field of your
Personal Preferences to Graceland, though this "Easter Egg" could later
interfere with dialing. A picture of a newt reappeared briefly whenever you
woke up your Newton. Other wakeup pictures can be obtained by adding two or
three spaces after your Address]. You should discount any allegations
suggesting any relation between Newt, Olivia Newton-John, Newton Minnow,
Senator Newt Gingrich or football great Knute Rockne. For crossword puzzle
fans, "eft" is an old term for "newt". Finally, newts have been hatching
aboard the space shuttle Q "one small step for a newt, a giant leap for
newtkind".


For Further Info
Since I provide little description of Newton syntax, other functions, or
curriculum ideas in this introductory file, I strongly recommend that you stay
reasonably close to the examples that I provide, register Newt to obtain a
more detailed manual and sample sources, wait for NS books to be published
(there is an introductory book by McKeehan&Rhodes for $29.95 with demo version
of Mac NTK), and/or buy the NTK and docs from APDA for $795. Take a look at
the NewATut and NewtTurT Newton books, which are interactive tutorials
(weyer@guest.apple.com).  PIE Developers magazine is a source of practical
programming information (cds@netcom.com).  Join the NANUG user group -- 
fun and useful (marku@aix3.ema.com).


Registration/Shareware and Freeware
Newt is my first shareware offering; earlier, I distributed a freeware game
"PicoFermiBagels". I debated whether to cripple this version by not allowing you
to save any or many methods or to automatically quit after awhile if you had not
registered, but I decided that I would rather spend my time figuring out how to
add new functionality rather than disable existing features.

Registered users receive a printed manual including an introduction to
NewtonScript, information about additional methods, and selected source
examples (see list) on floppy. I welcome comments, suggestions and questions,
and will respond as time permits. Minor updates to the basic Newt package and
examples will generally be free, especially if distributed over a network.
However, I reserve the right to charge additionally for major upgrades, for
additional modules or other services.

The registration fee for Newt 2.4 is currently $35 (for both US and
international users); checks preferred; no Visa yet -- pointers to
convenient, low-overhead credit card services appreciated). Compuserve users
can register online (GO SWREG; Newt's ID#: 3143; additional $3.50 S&H charge
to help defray part of 15% cost of this service). Current registered users
can send $7 to obtain the latest manual on paper, and documentation, releases
and source examples on a Mac or PC floppy (see change24.txt).  If you have an
email address, please include it so that I can inform you more easily of
updates, new examples, etc.

RUNewt, for later launching and transfer of Newt-generated apps, is free to
end-users; if you like it, I ask that you send email to my kids (America
Online: Krisbo and EllieJelly; internet: EllieJelly@aol.com, Krisbo@aol.com),
postcards, and/or other valuable tokens of appreciation. Developers can
contact me about invoking RUNewt from their applications, and bundling the
latest (or custom version) of RUNewt with their applications. [runewt-24.sit/
.zip/.hqx]. Slurpee is a free utility for transferring data and text between
Newton and desktop systems. [slurpee-12.sit/.zip/.hqx]

If after a few days of trial use, you find Newt useful and would like to
continue using it with a clear conscience and have the additional benefits
just mentioned, please stop procrastinating and register. I know this sounds
like a pledge break for National Public Television/Radio, but that is the kind
of user participation and support that shareware deserves and needs. If you
are still not ready to register, don't be afraid to send email -- to ask more
about what Newt already provides or tell me what it should have. Knowing users
are out there, with some occasional words of encouragement and praise, are
important. Money confirms that, covers some costs, and helps justify spending
a little more time on Newt in preference to other family or business pursuits.
To register, tap overview, select About Newt, then tap Save (in Eval Controls)
before exiting to create a registration form in Newt's current Notepad folder
to print, email, etc.


Current List of Examples/Packages (available to registered users):
- Newt-24L.pkg -- Newt lite omits Newt Drawing, Newt Controls,
                  registration form) [~16K smaller]
- NewtPFB.pkg  -- tutorial (like NewtATut) for Pico Fermi Bagels game

- applic1,2,3.nwt -- several variations on applic0.nwt for defining apps,
  changing values, other simple objects

- books.nwt    -- three examples of creating stand-alone Newton books. warning:
  the initial programmatic interface for specifying style and layouts is ugly. 
  This first version will likely evolve if there is interest and feedback from
  users.  see also helpapp1.nwt

- calcsci1.nwt -- a scientific calculator

- codetemp.nwt -- Newt's "Code Templates" palette for entering strings, functions,
  methods and slots

- fibonacc.nwt -- compute/benchmark several implementations of Fibonacci series

- formula1.nwt -- add formulas to the built-in Formulas app

- graphic1.nwt -- followup to graphic0.nwt. cCurve documentation. other
  recursive patterns: dCurve, fractal, fractalx, hilbert, tree; squiral2
  (interruptible version of squiral that draws in background process)

- helpapp1,2.nwt -- create an online help book embedded in an application
  (two syntactically different versions)

- kr-lett1.nwt -- original, partial version of Kristina's letters (appeared in
  NANUG _protoReality 1.3; see kr-lett1.art)

- kr-lett2.nwt -- complete version of Kristina's letters (appeared in
  NANUG _protoReality 1.4; see kr-lett2.art)

- libconst.nwt -- can be loaded to define constants for viewFlags, viewFormat,
  viewJustify, viewEffect, viewFont, bitmaps, sounds, dates, ....

- libproto.nwt -- complete set of prototype templates that can be customized,
  copied from a library folder.

- life.nwt -- a version of the "game" (mathematical simulation) of Life

- logo1.nwt    -- extensions for Logo-style commands: wordP, sentenceP, first,
  butFirst, last, butLast, word, sentence, reverse, wordToSentence,
  sentenceToWord

- pickers.nwt  -- examples of selecting from (long) lists using
  protoLabelPicker, DoPopup, A-Z index (protoPickIndexer), scrolling text list
  (protoTextList) and protoPicker
                
- picoferm.nwt -- source for Pico Fermi Bagels game (PFB 1.2), including help
  book (see helpapp1.nwt); also see NewtPFB (interactive tutorial)

- protos1.nwt  -- examples of prototypes (also see libproto.nwt): protoApp,
  protoStaticText, protoTextButton, protoPictureButton, protoCheckbox,
  protoRCheckBox, protoInputLine, protoLabelPicker, protoLabelInputLine,
  protoBorder, protoGauge, protoDivider, protoSlider, protoRadioCluster,
  protoRadioButton, protoPictRadioButton, protoPictIndexer
                
- protos2.nwt  -- examples of more prototypes: protoFloater, protoTitle,
  protoStatus, protoStatusBar, protoCancelButton, protoCloseBox, protoFloatNGo,
  protoFolderTab, protoFilingButton, protoRecToggle, protoGlance, protoSetClock,
  protoTextList, protoTable, protoTableDef, protoTableEntry, protoExpandoShell,
  protoTextExpando, protoRoll, protoRollitem, protoRollBrowser
                
- protos3.nwt  -- examples of more prototypes and viewclasses: protoDrawer,
  protoDateExpando, protoPhoneExpando, protoActionButton, protoPrintFormat,
  protoKeyboard, protoKeypad, protoLabeledBatteryGauge, clView, clEditView,
  clGaugeView, clKeyboardView, clMonthView, clOutline, clParagraphView,
  clPictureView, clPolygonView, clRemoteView (for protoPicker, see pickers.nwt;
  for protoEndPoint, see serialex.nwt & slurpee.nwt)
                
- serialez.nwt -- send/receive (or eval/print) a line of text between Newton
  and desktop terminal emulator

- slurpee.nwt  -- complete Newt source for Slurpee 1.2 utility. transfer
  paragraphs/tab-delimited text between soups and desktop terminal emulator

- soup1.nwt    -- simple database ("soup") example that creates a soup and
  lets you navigate/edit it
                
- soup2.nwt    -- simple database example to filter/modify an existing soup

- stopwatc.nwt -- track elapsed time for different activities


Many of the "DTS examples" (examples available to NTK users from Apple's
Developer Technical Support on ftp.apple.com:dts/newton) have been converted
to Newt format.  Most focus on several functions/features; some overlap with
other examples. The current DTS list includes (several examples still
undergoing conversion or testing are denoted by ***):

- a2zindex.nwt (protoa2z_TDS) functionality of the A to Z index in the
  overview of the Cardfile

- adspsamp.nwt (ADSP Sample) use CommToolbox and a terminal emulator for
  talking with Newton ***

- adjustob.nwt (AdjustoButton) buttons that automatically adjust themselves
  to obey the user interface guidelines on button spacing; also resize based
  on text contents

- agromodm.nwt (Agro Modem) terminal emulator and modem connection
  [*** waiting for new stable version]

- autorout.nwt (Auto Route) how to do routing without using a
  protoActionButton, as well as use the printerChooser proto

- auxform.nwt  (Aux Form) add an auxilliary info slip to print/fax slips

- buttnbar.nwt (ButtnBar) add buttons to a status bar the correct way

- buttons.nwt  (Buttons) some new tricks with buttons

- checkbk.nwt  (CheckBook) full application example; supports routing,
  filing, IA and Newton Connection ***

- chooser.nwt  (Chooser) set up a simple Chooser to look for printers etc.

- clock.nwt    (Clock) demonstrates idle script and some time functions

- datepick.nwt (DatePick) clMonthView-based date picker like the one found
  in the preferences or calendar app

- diffstrk.nwt (Different Strokes) how to capture ink and turn it into
  drawing objects for rendering on the screen, saving, etc.

- dot2dot.nwt  (Dot2Dot) capturing points for a dot-to-dot puzzle

- drawing.nwt  (Drawing) how to make, display and offset shapes

- dynapick.nwt (DynaPicker) dynamically change items in a protoLabelPicker

- expadate.nwt (Date Expando) text expando with date fields

- expanumb.nwt (Number Expando) expando item for numbers

- expaphon.nwt (Phone Expando) text expando with phone list

- expatime.nwt (Expando Time) custom expando item that edits a time

- extrachg.nwt (Extra Change) changes an app's icon (and text) in Extras

- falsalrm.nwt (False Alarm) how to set alarms ***

- fontscal.nwt (Font Scaling) how to scale fonts

- gauges.nwt   (Gauges) fun with gauges

- getpolyg.nwt (GetPoly) use points data structures

- glancing.nwt (Glancing) fun with protoGlance

- goodform.nwt (Good Form) store and retrieve records from a soup, also
  beam, find, use Newton Connection kit and file the entries ***

- greasysp.nwt (Greasy Spoon) "menus" with protoPicker

- handcrnk.nwt (Hand Crank) fast, low-level text drawing

- heavymet.hwt (Heavy Metal Disco) pitch shifting with sampled sound

- iatour.nwt   (IA Tour) Newton Dev Conf '93 Intelligent Assistant demo

- idleanim.nwt (IdleScript Anime) simple animation via viewIdleScript

- infobutt.nwt(Info Button) an "i" icon button that should be used for About,
  Help and Prefs in an application

- inspgadg.nwt (Inspector Gadget) run NewtonScript via Compile function

- irremote.nwt (IR Remote Sample) use IR functions for controlling
  consumer electronics applications ***

- irsample.nwt (IR Sample) how to write IR protocol applications ***

- irtimesy.nwt (IR TimeSync) Synchronize the date-time clocks of two
  Newtons via IR beaming ***

- keys.nwt     (Keys) how to do a keyboard, including using a picture for
  a keycap and using strings for what the key prints out

- letter.nwt   (Letter) three ways to perform letter-by-letter recognition

- littlepr.nwt (The Little Prints) minimalist approach for print and fax

- londcall.nwt (London Calling) phone number conversions

- modal.nwt    (Modal Fun) an application modal dialog

- newtextf.nwt (New Text Funcs) shows TextBox and TextBounds functions

- noselect.nwt (No Select) use ClearSelectionHilites (a platforms file
  function) to unselect selected data in a view

- notarize.nwt (Notarize) how to transfer data from your app to Notepad

- parascrl.nwt (Paragraph Scroll) one way to scroll a clParagraphView

- pictbuts.nwt (Picture Buttons) changing icons of picture buttons

- pictindx.nwt (Pict Index) using protoPictIndexer, which allows you to
  specify a large picture as a series of selectable small pictures.

- preefmad.nwt (Preefer Madness) how to add your own panels (views) to
  the system preferences and formula roll ***

- prototab.nwt (Proto Table) scrolling and updating of protoTable

- pseudins.nwt (Pseudo Inspector) eval stuff over serial connection

- qwerty.nwt   (Qwerty) on-screen keyboard without "add-to-dictionary?"
  prompt or "dictionary" icon

- radioclu.nwt (Radio Cluster) demonstrates radio button cluster

- rectoggl.nwt (Rec Toggle) recognition toggle button (e.g., in notepad)

- rollbrow.nwt (Roll Browser) roll browser example

- scrollpi.nwt (Scroll Pict/Over) 2D scrolling of larger views within a
  clipping view via two methods: totally custom; built-in proto

- sendcard.nwt (Send Card) how to put multiple things into the outbox

- serialex.nwt (Serial Example) simple serial communication example

- shellgam.nwt (Shell Game) how to keep 2 side-by-side shells in sync

- showbar.nwt  (Show Me to the Bar) basics of setting up a protoShowBar

- simpdial.nwt (Simple Dialer) mainly demonstrates the root's :Dial()
  method, and secondarily demonstrates how to set up a protokeyboard

- sizedrag.nwt (Size Doesn't Matter) drag to change the size of a view

- soundadv.nwt (Sound Advice) import, play sounds

- soundtrk.nwt (Sound Tricks) a couple of tricks with sound

- souphack.nwt (Soup Hacking) some useful Soup functions

- soupshow.nwt (Soup Show) how to display data (without creating soups)

- souptour.nwt (Soup Tour) simple walkthrough of many store and soup
  functions

- splashsc.nwt (Splash) a splash screen that is visible while the
  application is opening and an about slip using new Info button

- strange.nwt  (Strange Changes) example for studying when certain scripts
  are called in a clEditView

- supslurp.nwt (Super Slurp) create soups, xfer data over serial
  connection at 57.6K [see slurpee.nwt] ***

- syncscrl.nwt (Sync Scroll) how to use SyncScroll and how to use the
  'height' slot correctly with view templates

- tablist.nwt  (Tables and Lists) demo of protoTable and protoTextList

- tabstyle.nwt (Tabs and Styles) tab & style info in a clParagraphView

- textlist.nwt (Text List) how protoTextList works

- truegrid.nwt (True Grid) 3 ways to do scrolling "grid" views based on
  soup data ***

- undoredo.nwt (Undo Redo) demonstrates registering Undo, and an attempt
  at Redo

- unholydr.nwt (Unholy Drawers) create your own "drawers" like Extras

- upinsmok.nwt (Up in Smoke) how to achieve the ever popular
  smoke/poof/scrub effect

- viewscrp.nwt (View Scripts) illustrates order of form, child, done, and
  drawing scripts

- waksleep.nwt (Wake Up and Go to Sleep) detects when the Newton wakes up

- wallymat.nwt (Wally Math) uses the Compile function to take written
  mathematical input and run it as newtonscript

- wordarry.nwt (Word Array) how to access the recognition engine's
  statistics regarding most-likely words and confidence scores

- wrapitup.nwt (Wrap it up) 2 dynamic ways to change the height of
  clParagraphViews based on their contents

Finally, I encourage others to share their example code, either on your
own or through me.  For example, Serg Koren (archimag@netaxs.com) has
posted his Sieve and Post Office examples.


Programming WARNING -- Newt and You
Exploring "mathematics microworlds" and doing problem solving by writing
programs are "powerful ideas" (Seymour Papert) and require some active
participation by you the learner -- taking risks and making mistakes. For
example, Newt allows you to execute arbitrary NewtonScript expressions. This
can be a formula for enlightenment or disaster. So, remember that this is your
Newton with your information and listen to your mother's advice about backing
up your system and hanging out with strange functions.

Using common sense in following examples and suggestions, and limiting yourself
to documented commands, you should reap many benefits and long hours of
enjoyment from using Newt. At the same time, "a little learning [about
programming] is a dangerous thing" (with apologies to Alexander Pope). I would
caution against experimenting with random functions or methods. "Gee, I wonder
what xxx does" might yield a simple error box, or it might zap a frame or soup
in your system.

At the same time, given the litigious nature of our society that yearns for
risk without responsibility, I feel compelled to add the following warning
(repeated in other variations several places later):

  >>> WARNING: USE THIS PACKAGE AT YOUR OWN RISK! <<<

=====

Getting Started

Where to Find Newt, RUNewt, Slurpee, NewtATut, NewtTurT,...
Presumably, you have already obtained Newt or you would not be reading this. A
compressed file usually named newt-devenv-vv.sit or .hqx (vv = version number,
e.g., 2.4 = 24) should contain Newt-vv.pkg and NewtNews.txt; runewt-vv.sit or
.hqx should contain RUNewtvv.pkg and RUNewt.txt. See Newt.1st for servers/sites.

- Install Newt using Connection Kit (or other package downloader).

- Download examples. Earlier versions of Newt had some built-in demos. To save
space and to distribute more examples and source, I have provided these
separately in applic0.nwt and graphic0.nwt.  You can, of course, enter the
source yourself via handwriting and tapping Newton's "keyboard" (see Edit
Methods).  However, to save time and minimize syntactic errors, I would
recommend transferring the text from applic0.nwt and/or graphic0.txt.  You can
copy/paste text between ----- into the Notepad of Connection Kit and then
Synchronize.  Or, you can use a terminal emulator program on your desktop
computer with either Slurpee or Figgle's Typomatica to transfer chunks of text
to separate Notepad entries. You can put everything in Unfiled or existing or
new folders and mix with other notes, though I would recommend putting source
entries for separate apps/files into separate folders.

- Start Newt from Extras (or from NewtATut or NewtTurT)

- Tap overview and select About Newt. You can tap Save (located in the bottom
  Eval Controls) to save a registration form to your Notepad. close About Newt.


Exploring Newt's Turtle Personality
-----
Try the following (see also the NewtTurT interactive tutorial):
- select the folder at top of screen containing your sources. Newt
  compiles/checks any methods and object definitions (if there are problems
  listed, see Errors).
- tap the overview dot (between two scroll arrows in bottom menu)
- select Newt Drawing; then select Newt Controls.

- write a number into the input field to the right of Dist, e.g., 80. tap Dist.
- write a number into the input field to the right of Deg, e.g., 90. tap Deg.
- write a (small) number, e.g., 4, into the input field to the right of Times.
- tap Times.
- tap Newt? checkbox to hide Newt(s) for faster drawing. tap it again to show.
- tap Erase. tap Home.
- tap Expr button (in Eval Controls) and select different expressions (defined from
  graphic0.nwt); you may wish to Erase, Home between each.
- edit values for times, dist, deg (if these are used as parameters)
- tap Eval button (in Eval Controls).
- draw a picture that you like, tap Save (later check current folder in Notepad).
- drag Newt to another location and Eval an expression again.
- select and Eval the :addNewt expression from the Expr list.  This creates
  multiple Newts.
- select and Eval another expression like :squiral(8,40) -- this demonstrates
  broadcasting messages to multiple Newts. The Erase and Home buttons work on
  all Newts together, or you can use gestures on a specific newt, e.g., scrub,
  or messages, e.g., the newt1 expression.
- (optional) close Newt Drawing and Newt Controls


Exploring Newt's Application Personality
-----
Try the following (see also the NewtATut interactive tutorial). (You should have
RUNewt installed if you want to be able to Save your application):
- select the folder at top of screen containing your sources.
- tap the Expr button (in Eval Controls)
- select the expression :doObj('add,'MyApp)
- tap Eval
- select MyApp from the popup -- a application view with title appears
- tap Eval, select MyApp.myInputProto -- a user prototype object is defined in
  the running application (to be used by num1 and num2 fields)
- tap Eval, select MyApp+button -- this dynamically adds a button to MyApp.
  you can tap on the button; if the About box (float) has not yet been created,
  you will hear a sound
- MyApp+float -- this adds a floating view dynamically
- MyApp.float+aboutText -- adds a basic text object. close the floating view.
  now tap the About button
- MyApp+num1 -- this adds an input field that expects numbers.  You can write a
  number in the field, or double-tap for a calculator keypad.  When the total
  object exists, it will be updated.
- MyApp+num2 -- adds a second input field
- MyApp+round -- this adds a checkbox that makes total an integer or real
- MyApp+total --  this displays the total of num1 and num2

Hopefully, you have followed these steps correctly/successfully, and have a
functioning application. If you have RUNewt installed and your application is
visible
- tap the Save button
- exit Newt (get to Newt's close box by closing your application & other views)
- tap RUNewt, select an application title, i.e., Hello World.
- tap action button and select Run App
  
This quick tour should give you a basic idea of some of Newt's capabilities.
Although there is a more information in this file describing Newt's interface,
there is almost none regarding NewtonScript syntax or Newt's methods. If you
would like more documentation and examples, register!

=====
Interface Guide

The following sections cover the major interface areas of Newt -- the views
available by tapping overview (the dot between the two fixed scroll arrows at
the bottom of the screen).

Main View (Edit Methods/Objects)
This is the initial screen where you browse and edit objects and methods. Other
views (windows) are used for drawing, printing, building applications, and as
control palettes.

overview
Tap the overview dot (between the fixed scroll arrows) to pop up a list of
current views, containing built-in views such as About Newt, Newt Drawing and
Eval Log, palettes such as Code Templates, Eval Controls or Newt Controls,
RUNewt and Slurpee (if installed), and any user-created applications, e.g.,
Hello World. You can also add NTK apps/books to this list.

scroll arrows
In Edit Methods (Main View) or Eval Log (if visible), the main text field
scrolls.

folder tab (top of screen)
Newt uses the folder label for organizing "newts" for Save in Edit Methods
(Main View), Newt Drawing, Eval Log, and About Newt.  Newt "compiles" (i.e.,
makes an executable version of) methods and checks objects found in the
current folder, and notes errors (if any) in Eval Log.

source name
The name of current object, method or page appears in a "picker list", preceded
by a diamond.

action button (envelope icon)
You can Save and Revert, Duplicate, Delete current source.  You can also copy
templates from a library folder.  Newt does not currently provide a filing
button -- however, you can look at, reorganize, print, fax, beam etc. your
saved newts (methods, screen snapshots, print results, registration form)
outside Newt in the generic Notepad application.

We will now cover the other palettes and views, and return to editing and
creating methods later under Edit Methods (continued).

Eval Controls
The following controls are found in a floating, draggable palette, located
initially at the bottom of Newt's screen: Eval field, Expr, keyboard icon,
Eval button, Print?, and Save. As a general rule, you will want to keep Eval
Controls visible, rather than closing and re-opening it.

Eval field
This field can contain a short program in NewtonScript. Tap the Eval button to
execute it. Techniques for entering expressions include combinations of
- handwriting -- not great, given the amount of punctuation needed
- copy & drag text selections to/from the margin "clipboard"
- tap the keyboard icon for a floating kbd without "do you want to add" prompts
- double-tap for the default alphanumeric keyboard and use extra spaces
  around NewtonScript punctuation to prevent spurious prompts
- keyboards, e.g., KbdPro, or "reverse terminal emulators", e.g., Typomatica
  (Figgles Utils)
- tap Times in Newt Controls to fill in a standard "for" expression
- select complete expressions from the Expr list
- use the variable names times, dist and deg, so you can change numbers in
  the Times, Dist and Deg fields in Newt Controls rather than in the middle of
  the Eval field.
- select partial expressions from the Code Templates palette
- tap items in Newt books like NewtATut

Expr
A popup list of sample expressions appears -- you can customize this. If you
select an expression, it appears in the Eval field. You can then edit it,
and/or tap the Eval button to execute.

keyboard icon
This toggles (either shows or hides) a floating alphanumeric keyboard that does
not prompt for additions to the dictionary. You can double-tap in the Eval
field for the standard keyboard.

Eval button
Tap the Eval button to evaluate (compile and execute) the expression in Eval
field. The button remains highlighted during execution. (During interruptible
methods, e.g., squiral2, it changes to Stop and you can tap it to terminate
execution.) If you spell something incorrectly, or use incorrect parameters or
syntax, Eval Log (or a system error box) will appear with a somewhat cryptic
error message or code (see Errors). Basiclaly, you will have to compare what
you wrote more carefully against the example, edit it and try again. (Other
info and examples available to registered users).

WARNING: NEITHER NEWTON NOR NEWT PROVIDE A GENERAL INTERRUPT CAPABILITY. SO,
UNLESS YOU LIKE USING THE MANUAL RESET BUTTON IN THE BACK, USE COMMON SENSE IN
CHOOSING VALUES FOR ITERATION, RECURSION OR DISTANCE THAT ARE NOT "TOO LARGE".
I will generally provide some reasonable values to try. Newt's default
behavior is to finish executing the entire expression before checking for user
actions like button taps. There is a facility provided in Newt to replace the
NewtonScript "for" iteration construct. This facility executes each step in
the background, allows you to interrupt Newt, and is covered in the manual.

Print?
If checked (default: no), the Eval Log view pops up with expression and results
after you tap the Eval button. Error messages will appear regardless of this
setting.

Save
The current (top) view is saved, usually to the Notepad under the current
folder tab category. For Edit Methods, the method source, if edited, is saved
(same as Save under action button). For About Newt, a text registration form
is saved. For Eval Log, the current printed results are saved. For Newt
Drawing, the current drawing, if any, is saved. A user Application is saved
to an application soup, if RUNewt is installed. If the view is not recognized,
Newt beeps.

Newt Drawing
Newt's drawing area appears when you select it from overview, use Newt
Controls, or evaluate an expression using drawing methods. You can use the
following gestures to operate on the Newt closest to the start of the gesture
(if you have multiple Newts).
- tap
  Newt moves to location of pen using current Pen setting, preserving heading.
- line
  Newt sets heading to orientation (mod 45 degrees) of line. If Newt is already
  headed in that direction, it draws a line of same length (rounded to mod 10)
  of your gesture.
- scrub
  same as Erase
- drag
  Hold down on a Newt until you "hear a squeak and get a fat pen" (actually the
  "hilite" gesture). Then, drag to a new location before lifting pen. Newt moves
  to new location without drawing.

Use the Save button in Eval Controls to save the current drawing in the Notepad
under the current folder tab category. Newt currently "remembers" the current
drawing when you close and re-enter Newt Drawing.

Newt Controls
Select this floating, draggable palette via overview. It is located initially at
the top of Newt Drawing. and contains the following controls: Erase, Home,
Pen, Color, Newt?, Times button & field, Dist button & field, Deg button &
field. Like keyboards and Eval Controls, it can be dragged by its bottom
border.

Times
The value in this field (default: 0) can be used as a times variable in the
Eval field. The Times button uses this value to create an iteration, e.g., if
Times=4, Dist=40, Deg=90, tapping on Times tells Newt to :go(40) then
:turn(90) 4 times, i.e., making a square -- the NewtonScript is written to the
Eval field where it is executed immediately (and you can edit it later if you
like). Tap Deg to turn, then tap Times or the Eval button again to see what
happens.

Dist
The value in this field (default: 0) can be used as a dist variable in the Eval
field. The Dist button uses this value for distance, e.g., if Dist=20, tapping
on Dist tells Newt to :go(20), moving 20 in the "forward" direction, i.e.,
along Newt's current heading. This draws a line if Pen is non-zero. A negative
value for dist just means go "backward". To give you some idea of scale,
Newt's default drawing area on MessagePad is roughly 228x310 (on a MP100).
Newt clips at its drawing boundary.

Deg
The value in this field (default: 0) can be used as a deg variable in the Eval
field. The Deg button uses this value for degrees, e.g., if Deg=90, tapping on
Deg tells Newt to :turn(90), turning right (clockwise) by 90 degrees. A
negative value just means turn left. Newt will "mod" your number to prevent
dizziness.

Erase
Newt erases drawing area, and remains with same position, heading and pen.

Home
Newt teleports to center, sets heading to 0 ("up"), preserving pen setting but
without drawing.

Pen
Newt sets pen thickness used in drawing (default: 1) and grows or shrinks in
size. 0 means Newt just moves (no line)

Color
Newt sets pen pattern used in drawing (default: black). Currently, this color
is not available in saved Notepad drawings (everything is black).

Newt?
If checked (default: yes), Newt appears with its tip at current x,y position,
pointing in current direction, and "xor-ed" so that it does not interfere with
drawing.

About Newt
Select this via overview. Tap Save in Eval Controls to create a registration
form in Notepad under the current category (see folder tab) for later
printing, mailing, etc.

Code Templates
This is a separate floating, draggable palette accessible via overview, located
initially on the right hand side of the screen. This can be used for Eval
field, but is most useful for method source in Edit Methods (Main View). As
you select items from the text list, a template is inserted into your current
method. Customizing this list is described in the manual.

Eval Log
See earlier comments under folder tab, scroll arrows, Print? and Save.
 
RUNewt, Slurpee, NewtATut, NewtTurT, etc.
If you have RUNewt installed on your Newton, it will appear in overview, where
you can select it in order to run earlier Newt-created applications -- see
RUNewt.txt for further info.  If Slurpee is installed, it will also appear in
this list.  If you have started Newt from NewtATut or NewtTurt, titles for these
will appear here also. You can also add other NTK packages (apps and books).

Your Applications
overview also contains the titles of applications you are currently developing
within Newt, based on source methods. Once you Save the application as a frame
object, it is available separately via RUNewt.


Edit Objects/Methods (continued)
We now complete coverage of the interface by revisiting the main view.

source names
A "picker" at the top preceded by a diamond contains methods, objects and pages
defined in current folder (see folder tab). The diamond disappears during
editing (see Save, Revert). You can also select one of the "new" names at the
top of the menu to create a default template.

source text
As in the Eval field, you can use handwriting, copy&drag and keyboards to edit
your method, object or page source. You can change its name by editing. You
can Save, Revert, Duplicate or Delete it via the action button on right.
Conventions for different kinds of methods and objects and NewtonScript syntax
described in the manual.  Also look at graphic0.nwt and applic0.nwt for
examples.

action button
- Save
Assuming that the source name is valid, does not conflict with a pre-defined
"system" method, and successfully compiles, the method source is saved
(created or updated) as a "newt" (i.e., text Note) in the current folder.
Errors, if any, are noted in Eval Log. Newt saves only valid sources. So, if
you cannot figure out a compile error from the cryptic message, you could
either Revert to the earlier version, or comment out offending code (precede
individual lines with //, or wrap a section with /* <lines of code> */), so
that you can Save for now, get on with your life, and look at it later. 
Methods are defined immediately; other objects are only checked but can be
added explicitly later, e.g., via :doObj.

- Revert
If you have unsaved changes, the diamond in front of the source name disappears.
Revert returns to the last version saved of the original method in the current
folder, or to the basic template.

- Duplicate
This makes a copy of the current source. Give it a new name (no duplicate names
allowed).

- Delete
Deletes current source from Notepad. It also deletes defined Newt method (if any)
but does not delete existing objects.

- Copy from
Copies object, method or page template from a designated library folder.


Preferences
Newt saves your preferences for Pen, Color, Newt?, Print?, folder tab and
library folder in a small "system soup" frame that persists across Newt
sessions. If you no longer need Newt, you can remove this preferences frame
via a soup utility or directly from Newt (evaluate
EntryRemoveFromSoup(prefsEntry) just prior to exiting Newt).

=====
NewtonScript
Syntax
If you have already tried the examples and expressions outlined in under
Exploring Turtle or Application, looked at the examples in applic0.nwt and
graphic0.nwt, then you should have a rough idea of what NewtonScript (NS)
syntax is like and several of Newt's commands. In NS, programs or scripts are
defined as "methods" on objects. Methods describe an object's behavior or
actions. Objects in NS are called "frames" (perhaps they should have been
called "newtrons"), which inherit attributes and behavior from other frames,
usually called "prototypes". Newt is a prototype or kind of view. You tell
Newt to do things by sending it a "message", e.g., go. This message consists
of a frame (Newt implicitly), a colon (:) separator, the method name, and
parentheses with zero or more parameters (values for variables) separated by
commas. For example, :go(50). A frame also has "slots" (named attributes) that
contain values that you can access, such as times, dist, and deg. You can just
use the slot name if it can be found via inheritance, or frame.slot if you
want to be more specific.

WARNING: IF YOU USE OTHER SYSTEM FRAMES, METHODS, AND FUNCTIONS BEYOND THE ONES
I HAVE DESCRIBED HERE AND IN EXAMPLE FILES, YOU DO SO AT YOUR OWN RISK.

For further information on NewtonScript syntax and view frame slots and
methods, NTK from APDA includes manuals, and other books will be published.
The Newt Manual provides a summary of syntax and built-in functions, along
with additional Newt methods for registered users.

Errors
In the unlikely event that a system box pops up with a cryptic error code
during Eval or Save, check the following partial list of common error codes,
and see if there might be something missing or extra in one of your values or
expressions.

Table 1: Common Error Codes
Code      Description
-8007     syntax error (from compiler)
-48404    expected a number
-48402    expected an integer
-48803    wrong number of arguments
-48807    undefined variable
-48809    undefined method
1627052   divide by zero

There is a Newton book (newton.uiowa.edu/newton/software/books/error-book.hqx)
that lists errors from the NTK docs. If you have a Macintosh, the Newton
LowDown DA (newton.uiowa.edu/newton/misc/lowdown-da.hqx) may be useful.

Things to try: check your syntax against those in examples, check spelling for
method and variable names, missing or extra punctuation, garbage from stray
gestures, check number and type of arguments (e.g., float vs. integer), and in
general use your "newtle". If you think it is really a problem with Newt, send
me mail describing what you had entered, and I will try to respond asap.

The manual provides basic coverage of NewtonScript syntax and some
built-in functions. It also documents methods for creating
applications, customizing Newt, drawing with it, and accessing other system
functionality. Description and examples of specific system prototypes are
provided in separate files (see earlier Current List of Examples).

=====
Possible Next Steps
There are many features and fixes that would be nice to have. However, there
are also design trade-offs, especially given the MessagePad's and my
constraints. So, help me figure out:
- where can it go on the screen?
- how much memory space and implementation time is it worth?
- can it take advantage of existing Newton mechanisms or metaphors?

For example:
- resizable views (hooks are in there; need better system support)
- save applications as "real" Newton packages (need docs), access via Extras
- palette for app objects with interface support for drag, edit, etc.
- more online manuals, tutorials
- more example files
- better drag gesture; other gestures for drawing; undo support for drawing?
- use Newt as a wireless remote LegoLogo controller
- allow more customization of Newt environment, save more to Preferences?

=====
Personal History
I first implemented a screen turtle on an IMLAC display computer, accessed from
BBN Logo on a DEC PDP-10 at Stanford circa 1973. Subsequently, I implemented
other versions in Lisp, and used others in Smalltalk and ObjectLogo. My
long-time interests in children, learning and programming environments, plus
two small NTK examples, Dot2Dot and InspectorGadget, with a little creative
juxtaposition, started me down this path. Experience with using and
implementing object-oriented browsers and toolkits in Smalltalk and Lisp and
numerous user requests led to the Newt 2.x enhancements to support application
development. When I am not working on Newt at home or trying to have a life, I
am consulting, currently for pharmaceutical companies, on "enabling
technologies", in particular, pen-based systems.

Credits
Newt 2.4 was created with NTK 1.0.1. Newton and Newton ToolKit are trademarks
of Apple Computer. Kudos to Apple for creating an exciting product (Newton),
and powerful object-oriented language (NewtonScript) and development
environment (NTK). I look forward to new versions of NTK, documentation and
examples.

My family contributed the evening and weekend time for me to explore this;
Ellie and Kristina helped with testing, Maria with proofreading. Finally,
thanks to the users and testers who have given me feedback and encouragement.
I hope that Newt can continue to evolve into an environment that meets your
needs.

